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Introduction 


AP127.EXE emulates the IBM APL2 and Sharp APL AP127 auxiliary processors. This product is meant to 
be used with Dyalog APL for MS Windows by Dyadic Systems Ltd. 


AP127 is a DDE client application and communicates with Dyalog APL/W via one shared variable. 
Generally, input and output data formats match to appropriate data formats used in AP127 on a mainframe. 
AP127 uses the Microsoft Open Database Connectivity (ODBC) standard which allows you to reach any major 
database directly from Dyalog APL. AP127 enables an APL user to use Structured Query Language (SQL) to 
communicate with a relational database. AP127 passes SQL statements to a database manager and returns 
data, if any, back into the APL workspace. Users who are not familiar with SQL should read the appropriate 
manuals before using of AP127. This document includes all necessary information on AP127 programming. 


AP127 requires that you have Microsoft ODBC 2.0 installed on your computer. Note that Lingo Allegro is not 
authorized to distribute ODBC drivers. Please contact Microsoft Corp. or your database vendor to obtain the 
necessary ODBC drivers. 

AP127 is a program product by Lingo Allegro USA, Inc. 

The following (or equivalent) manual may be used during AP127 programming: 


SHARP APL/370, Programming Reference, Release 19. 
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1. AP127.EXE Command String Format 


Before you start the AP127 program, the Dyalog APL/W system must be prepared to share a control variable 
(see section 2). 


You may run the AP127.EXE program either from an APL/W session or from the Windows File Manager. 
Normally, you should include at least two parameters in the command string which runs AP127. These 
parameters are separated with blanks, and each parameter begins with "-" (except connection string). You may 
include up to four additional startup parameters. The general format is as follows: 


AP127.EXE -wsid -extname -t<number> -h <connection string> 


where: 

wsid - the server name: the name of the APL/W workspace (may include a path) in which the control 
shared variable is defined; if you execute the command string in an APL/W session, this parameter 
is the current value of QWSID; if this parameter omitted, the string "SERVER" will be used; 


extname - the external name of the shared variable (see next section for details); if this parameter is omitted 
the string "“EXTNAME" will be used; 


number - an integer that specifies login timeout in seconds; you should not use this parameter when 
connecting to a database on the same computer (an error message will be reported); for example, 


the token -t180 specifies a login time of up to 3 minutes. 


h - normally, when AP127 starts, its window is displayed as an icon (default option); using h 
parameter you can hide this icon and make AP127 invisible when you application runs. 


connection string - describes data source. If this parameter omitted, the ODBC dialog box that allows you to 
choose the data source will be displayed. If the connection string is "+", the AP127 will not make 
an attempt to connect to a data source. See the description of CONNECT comand for more details. 


If only one of the first two parameters is present, it is treated as the server name. 


The best way to start AP127.EXE is to use the [CMD system function from an APL session (see section 2). 
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2. Connecting AP127 With Dyalog APL/W 


You perform three steps to connect APL/W with the AP127 program. The first step is to make a general offer 
to share a variable defined in the current workspace. The workspace must have a name. The following 
example shows how to share variable X: 


)WSID EXAMPLE 

Xett 

'"DDE:' QSVO 'X EXT! 

1 

You should assign the variable X to be a valid AP127 command, because when the offer to share X is accepted 
by AP127.EXE the value of X will be passed to AP127 as the first command. You may use any valid AP127 
command, when you set the initial value of shared variable. However, it is recommended to use NULL 
command. EXT in the QSVO statement is the external name for X. You may use any valid name. This name 
will be displayed in the caption of the AP127 window. 


You may share any numbers of APL variables with AP127 and get access to more than one data source from 
same Dyalog APL workspace. However, you must use different external names for different APL shared 
variables. You should perform all steps described in this section for each APL variable you want to share. 
When new APL variable is shared, a new instance of the AP127 will be started. Thus, each shared variable 
acts independently 


The next step is to start AP127.EXE from an APL/W session or from the Windows File Manager. The best 
way is to execute the following APL expression: 


OCMD (path,'AP127.EXE -EXAMPLE -EXT') ''! 
where pat h isa path to the directory that contains AP127.EXE. 


The generalized method for running AP127 from your current workspace is as follows (using QWSID in 
the expression causes it to adapt automatically to any change in workspace name): 


PATH+'C:\WDYALOG\AP127\'! 
EXTN+*'EXT! 
OCMD (PATH,'AP127.EXE -',QWSID,' -',EXTN) '' 


PATH -isa global variable that contains the path to AP127.EXE. Having such a variable allows 
you to easily adapt your program to a different directory location for the executable file; 
EXTN -isthe global variable that contains the external name of the shared variable. 


The third step is to wait until the connection is established. It may take several seconds depending on the load 
on your Windows system, or even hundreds of seconds if you are connecting to a remote database. The wait is 
necessary because otherwise you may lose some of the first commands. Before the connection is established, 
there is no shared variable synchronization. You can be sure that all of your commands are passed and 
executed by AP127 only when the value of (OSVS 'X'){2] is 1. The following expression provides 
the necessary delay: 


[n] +(1#(QSVS 'X')[2])/OLC 
This expression will be executed until AP127 sets the returned value of the shared variable. This means that 
the offer was accepted and AP127 is ready to execute commands from APL. Then the user must set the shared 


variable control vector to1 4 1 1 (full interlock). The defined function SHARE from workspace AP127, 
shown below, includes all the steps necessary for linking APL/W and AP127 via shared variable X: 
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SHARE;A 
[1] a Exit if already shared 
[2] >+(2=SVO 'x')/0 
[3] a Be sure that variable is not in use 
[4] A+[SVR 'X' 
[5] a Set initial value (NULL command) 
[6] Xett 
[7] a Issue offer to share 
[8] A+'DDE:' QSVO 'X EXT' 
[9] a Load AP127. CONSTR - connection string 
[10] OCMD (PATH,'AP127.EXE -',QWSID,' -EXT ',CONSTR) '! 
[11] a Wait while it’s loaded 
[12] -+(12(O0SVS 'X!)[2])/OLC 
[13] a Set full interlock 
[14] 4< 1 Qsve 'X' 
[15] a Get returned value 
[16] >(1=2>X)/0 
[17] a Connection to ODBC failed. 
[18] a Put an appropriate code here... 


If CONSTR is empty character vector, then the ODBC dialog box will appear: 


QL Data Sources 





You should choose one of the data sources (see next section) and click the OK button. It may take some time 
while AP127 establishes the connection (when you are connecting to a remote database on a network, it may 
even take a few minutes). If you provide the full connection string in the QCMD command, the dialog box will 
not appear, and AP127 will establish the connection using the information from this string (see section 1). 
Refer to the documentation of your ODBC drivers for a the description of the connection string for your driver. 
In many cases you can use the result of the CONNECT command as a connection string for the current data 
source. 


If you have used the NULL command, as an initial value of shared variable, the first returned by AP127 value 


will be two-item nested vector (see the description of the NULL comand below). The second item is a simple 
one-element integer vector. Its element is 1, when connection to ODBC was successful, or 0 otherwise. 
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3. Configuring Data Sources 


Before you can use ODBC to communicate with databases, you must configure data sources. The term "data 
source" means the collection of the data a user wants to access, its associated database management system 
(DBMS), and the network (if any) to access that platform. Each data source requires certain information in 
order to connect to it. Usually, this information consists of the name of the data source, a user ID, and a 
password. Different data sources may require different connection information. The ODBC Administrator 
program stores the descriptions of data sources in a special file. Each data source has a name that allows you 
to distinguish data sources. For example, for Microsoft Access the description of the data source consists of a 
path to a database file, and the name of database file. 


To configure (define) a data source you should do the following: 


1. Run the Windows Control Panel utility: 


= Control Panel ae 
settings Help 


F © 


Ports Mouse Desktop Keyboard 


P B ke 


Printers Intemational Date/Time 0 Drivers Sound 


Btrieve_sdk20 (Btrieve Driver) 

csv_sdk20 (Text Driver) 

dBase_sdk20 {dBase Driver} 

Excel_sdk20 (Excel Driver) 

Fox_sdk20 (FoxPro Driver] 

MYTEST [Access Driver) 

Paradox_sdk20 (Paradox Driver) 

Sample_sdk20 (Template Sample Drive 
A : 
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eee 
SES 


Btrieve Driver 
dBase Driver 
Excel Driver 
FoxPro Driver 
Oracle 


Paradox Driver 





4. From the Add Data Source dialog box choose the driver which is able to support the database you are 
interested in, and click OK. For example, if you have chosen the Access driver, the following dialog box 


appears: 


ODBC Mi 





REN 
AASS, 





5. You should enter the necessary information to define your data source and click OK. Your data source will 
be added to the list of data sources. Close the ODBC Administrator and the Control Panel. 


The next time you run AP127 your data source will appear among the names of available data sources and you 
will be able to connect APL to the corresponding database. 
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4. AP127 Data Format 


Any value placed into shared variable X (see section 2) will be passed to AP127 as a request for a certain 
database operation. Variable X may be a simple or a nested vector (see command descriptions). The first item 
of a nested argument or entire simple argument must represent a valid AP127 command word. For example, 
the following expression represents the PREPARE command: 


X«'PREP' 'Si' 'SELECT x FROM ORDERS' 


Only one AP127 command can be used during the specification of the shared variable. 


Important Note: 

Because AP127 and Dyalog APL/W work in the full interlock mode, you MUST refer to the shared 
variable before setting its new value. It is highly recommended to use a special service function that provides 
the data exchange between AP127 and APL/W. An example of such a function is given later in this manual. 
You should avoid the direct use of the shared variable in application programs. 


The new value of the shared variable returned by AP127 has the form of a two element nested vector. The first 
item is a simple integer vector of 5 elements. The nature of the second elements depends on AP127 command. 


The first item of the returned value (called return code) is an integer vector of five elements. The return code 
has the following interpretation: 


- The first three elements indicate the type of completion: 
0 0 0 - Normal completion 
O O 1 - Normal completion, but possibly with incomplete table 
O 1 0 - Warning (operation was successful) 
1 0 0 - Error 


- The fourth element indicates the source of any error or warning: 


0 - Noerror 
1 - Error comes from AP127 
2 ~ Error comes from database management system 


- The fifth element is the actual error number (if any). 


The second item of the return value of the shared variable can be a nested matrix, nested vector, or simple 
matrix. If an AP127 operation does not have any return value, this item will be an empty numeric vector. For 
example: 


X+'PREP' 'Si't 'SELECT x FROM ORDERS' 
DISPLAY X 
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The following (or similar) function SAY from workspace AP127 can be used in application programs. It has 
one argument which is passed to the AP127. It returns the second item of the return value of shared variable 
(in this example X) as its result, if the operation was successful. It places the return code in the global variable 
RC. You may want to use a simpler or more sophisticated function in your programs. 


R+SAY A 
[1] a Issue AP127 request 
[2] X+A 
[3] a Wait while request is executed 
[4] RC R+X 
[5] a Analyze return code 
[6] >RC[2]+M1 
[7] 'WARNING: ',SAY 'MSG' RC 
[8] >0 
[9] M1:>RC[1]+0 
[10] 'ERROR: ',#RC 
[11] 'MESSAGE: ',SAY 'MSG' RC 
[12] a Your error processing here... 


This is an example that uses function SAY: 


SAY 'CONNECT' 
DSN=My Datebase;DBQ=c:\access\sample.mdb;FIL=RediSAM; 
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5. AP127 Programming Overview 


This Manual assumes that the reader is familiar with SQL. Please read an appropriate textbook or technical 
reference on SQL before programming AP127. This section gives quidelines for AP127 programming. 


The following steps are typically required for data manipulation using AP127: 


1. Sharing a variable with AP127 (see theSHARE function example in section 4). 

2. Connecting to a data source using AP127 command line parameters or the CONNECT command. 

3. Setting AP127 options using the SETOPT, MSG, and WAKEUP commands. 

4. Execution of operations on a database using the EXEC, PREP, CALL, OPEN, FETCH, etc 
commands. 

5. Commit or rollback transactions using the COMMIT or ROLLBACK commands. 

6. Repeat steps 4 and 5 as many times as necessary. 

7. Closing the connection by retracting the shared variable. 


The most important step is step 4, where actual data exchange takes place. There are two types of SQL 
statements: statements that return a result set and statements that do not return a result set. The SQL SELECT 
statement is a typical example of statement that always returns a result set (this set is a set of rows from one or 
more table and can be empty). The SQL INSERT statement is an example of statement that never returns a 
result set. You should choose an appropriate sequence of AP127 operations, depending on what kind of SQL 
statement you need to execute on the current data source. 


All SQL statements that return a result set must be prepared and opened. The result set must retrieved using 
FETCH operation. When all results are retreived, the statement must be closed and purged. FETCH function 
shown below, can be used for the execution of any SQL statement S without parameters and returns a result 
set: 


R«FETCH S 
C1] R+SAY 'PREP' 'SS' S 
[2] Re-SAY 'OPEN' 'SS' 
[3] R+SAY 'FETCH' 'SS' 0 'VECTOR' 
[4] Lis>+(RCA.=0)/L2 
[5] R+R; ° SAY 'FETCH' 'SS' 0 'VECTOR' 
[6] >L1 
[7] L2:S+SAY 'CLOSE' 'SS' 
[8] S+SAY 'PURGE' 'SS' 


Example of using FETCH function for data selection: 
FETCH ‘SELECT x FROM ORDERS WHERE ORDERID>100'! 
104 1994-05-26 123.45 


102 1994-05-26 345.89 
108 1994-05-30 23.78 


Example of stored procedure execution in Microsoft SQL Server: 


FETCH ‘EXECUTE sp_who'! 


1 sleeping Sa 0 master MIRROR HANDLER 

2 sleeping sa 0 master CHECKPOINT SLEEP 
3 sleeping sa 0 master LAZY WRITER UN 
4 runnable WEIL CH1i481 0 FCMS SELECT 


The FETCH function can be modified to execute SQL statements with parameters (see description of FETCH 
operation in section 7). 


SQL statements that do not return a result set can be executed directly using EXEC operation, or they can be 


prepared using PREP and executed later using CALL. SELECT statements can not be executed directly. 
Statements that return a result set may generate errors, if they executed directly. 
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Example of direct execution of INSERT statement without parameters: 


SAY 'EXEC' ‘INSERT INTO ORDERS VALUES(500,''1994-06- 
01'', 43.9)! 
1 


Example of prepared execution of INSERT statement with parameters: 
SAY 'PREP' 'S1' 'INSERT INTO ORDERS VALUES(?,?,?)' 
SAY 'CALL' 'S1i' (500 '1994-06-01' 43.9) 


SAY 'PURGE' 'S1' 


See section 7 of this document for detailed descriptions of AP127 operations. 
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6. Alphabetical List of AP127 Calls 


The following is the alphabetical list of supported AP127 calls. Detailed descriptions are given in the next 
section. Note that this list contains a few commands which were not available in AP127 on a mainframe. 
Except for these extensions, AP127 for Dyalog APL/W is fully compatible with AP127 by IP.Sharp for Sharp 


APL/370. 


CALL 
CLOSE 
COMMIT 
CONNECT 
DESCRIBE 
EXEC 
FETCH 
GETOPT 
INFO 

MSG 
NAMES 
OPEN 
PREP 
PURGE 
ROLLBACK 
SETOPT 
STATE 
STMT 
TABLES 
WAKEUP 


- sets parameters and executes prepared-in-advance SQL statement; 

- closes cursor for a SELECT statement; 

- commits transactions; 

- returns current connection string; 

- returns information about columns to be returned by a SELECT statement; 

- directly executes a non-cursor SQL statement; 

- retrieves rows of the result of the execution of a SELECT statement; 

- returns current system settings; 

- returns ODBC driver-related information; 

- controls the appearance of diagnostics messages and retrieves diagnostic messages; 
- returns a list of the names of prepared SQL statements; 

- opens a cursor for a prepared SELECT statement; 

- prepares an SQL statement for future execution; 

- deletes a prepared SQL statement from system tables; 

- rolls back transactions; 

- sets system parameters; 

- returns the state of a prepared SQL statement; 

- returns the text of a prepared SQL statement; 

- lists available tables in the current database; 

- defines actions which should be performed by AP127, when a timeout of inactivity expires. 
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7. AP127 Operations Reference 


It is assumed that X is the name of the AP127 shared variable and rc is the return code (see section 4) in all 
descriptions below. Some examples use the SAY function defined in section 5. Parameters in brackets ([ and 
]) can be omitted. This manual is a draft of the Programmer's Reference to be distributed in future. 


7.1. NULL Operation 


Format: Xett 


Arguments: None 


Result: rc N 

rc - return code; 

N - 1, if AP127 is currently connected to a data source, or 0 otherwise. 
Description: 


This operation does not perform any actions. It returns current connection status. Useful during 
connection to a database. 


Example: 

Xett 

DISPLAY X 
VEEE EE Be Ses 
| .>-------- <...>. | 
| 10 000 0] [1] | 
| Wes ts ar t tot | 
Ve is a is ae ees ee ee a eee a N 1 
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7.2. CALL 
Format: X+'CALL' NAME [(V1 V2 ... Vn)] 


Arguments: NAME -name ofa prepared non-cursor SQL statement (see PREPARE); 
Vi... - value list conforming to the parameter markers in the named SQL statement. The 
number of values in the list must be the same as the number of "?" marks in the 
SQL statement. Each value must be a scalar, a one element simple vector, or a 
simple character vector. Empty vectors are treated as NULL values (the 
appropriate columns must allow NULL value). The entire list of parameters should 


be enclosed. 
Result: rc n 
re - return code; 
n - number of affected rows; if the number of affected rows is not applicable to the 


SQL statement, or the current driver does not support this feature, the value of n is 
undefined. 


Description: 
This operation executes a non-cursor SQL statement that has been previously prepared. Most types of 
data manipulation and access SQL statements (except SELECT) can be executed by this operation. 
However, if the statement does not require a value list, or is only to be performed once, then the 
EXEC operation is more appropriate. 


If the fifth element of the result of the AP127 INFO command is 0, it means that the current ODBC 
driver counts the number of dynamic parameters (indicated by "?" symbols) in SQL statements. For 
such drivers AP127 returns an error only if the CALL operation did not have enough values in the 
parameter list to satisfy all parameter markers. If the value list contains more elements than "?" 
symbols in the SQL statement to be executed, then excess values will be ignored. 


If you have any problems using the CALL and OPEN commands with parameters, please contact 
Lingo Allegro for assistance. In any case you can avoid the use of dynamic parameters in SQL 
statements by applying the appropriate transformations in APL . 


Example: 


SAY 'PREP' 'Si1' 'UPDATE ORDERS SET ORDDAT=? WHERE ID=?' 
SAY 'CALL' 'Sit ('1994-05-25' 15) 
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7.3. CLOSE 
Format: X«'CLOSE' NAME 


Arguments: NAME -name ofa prepared and opened SQL statement (see PREPARE and OPEN); 


Result: re (20) 


re - return code; 


Description: 


This operation closes the cursor of a prepared and opened SQL statement. The statement remains 
prepared, so it can be re-opened again with a new value list. 


Example: 
SAY 'PREP' 'S1' 'tSELECT * FROM ORDERS WHERE ID=?' 


SAY 'OPEN' 'Si' 15 
SAY 'FETCH' 'S1! 

15 WHITE 1994-05-25 123.45 
SAY 'CLOSE' 'S1' 
SAY 'OPEN' 'S1!' 20 
SAY 'FETCH' 'S1'! 

20 BROWN 1994-05-28 327.89 
SAY 'CLOSE' 'Si' 


SAY 'PURGE' 'S1'! 
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7.4. COMMIT WORK 


Format: X+'COMMIT' 


Arguments: None 


Result: 


re (10) 


re - return code; 


Description: 


This operation saves all database modifications made since the last COMMIT or ROLLBACK. 
AP127 may perform different actions when executing this operation. If the third element of the result 
of INFO command is: 

0 - all prepared statements are purged (DELETE mode); 

1 - all opened statements are closed; they can be re-opened without preparation (CLOSE 
mode); 

2 - prepared statements do not change their states PRESERVE mode); 


If the second element of the result of INFO command is 0, the current ODBC driver does not support 
the manual COMMIT mode. That is, all transactions are committed immediately by the driver. You 
can't ROLLBACK transactions. 


By default, AP127 works in the AUTOCOMMIT mode. If the current ODBC driver allows the 
MANUAL COMMIT mode, you should use SETOPT command to set AP127 to this mode. 
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7.5. CONNECT 


Format: X«'CONNECT' ['constr'] 


Arguments: constr - if present, must be simple character scalar, or vector. 


Result: re str 
re - return code; 
str -a character vector, that represents the connection string which has been used by 
the ODBC driver to connect to the current data source, or empty numeric vector. 
Description: 


When this command is used without argument, it returns the current connection string. In most cases 
you can use this string as the last startup parameter when you start AP127.EXE. Because this string 
contains all necessary connection information for the ODBC manager, the initial dialog box which 
allows you to choose the data source won't appear. 


When this command is used with a parameter, the value of constr will be used by AP127 to find 
and to connect to appropriate data source. The current data source will be closed, all pending results 
and prepared statements will by purged. If the parameter contains enough connection information, 
the connection dialog box won't appear. Otherwise, a user will be prompted for additional 
information (this is driver dependent). In many cases it is enough to indicate the data source name, 
and the password, if it is applicable to that datasource. If constr is empty vector, usual ODBC 
connection dyalog box will appear. When the CONNECT command is used with a parameter, the 
second item of the result is empty numeric vector. 


General structure of the connection string is: 


PAR1=value 1;PAR2=value?2,...,PARn=valuen, 


Different ODBC drivers require different start up parameters PAR. Usually, you have to define the 
following three parameters: 
DSN -data source name, as it is defined in the ODBC Data Sources Manager program; 
UID - user ID, if your data source requires this information (DB2, MS SQL Server, etc.); 
PWD _ - password, if your data source requires it. 
If the data source requires more necessary parameters, or if you omit one or more of the above 
parameters, you will be prompted for them, when AP127 starts. Please refer to your ODBC driver 
documentation concerning the structure of the connection string. 


If you make a mistake in the connection string, and AP127 is not able to connect to a data source, you 
won't be able to use AP127 until you execute this command with correct parameter. When AP127 is 
not connected to a ODBC driver, only CONNECT and NULL commands are allowed. You may use 
the NULL command to check the current connection status, and to perform necessary actions. 


Example: 


SAY ‘CONNECT! 

DSN=My Datebase;DBQ=c:\access\sample.mdb;FIL=RediSAM; 
SAY 'CONNECT' 'DSN=Sales Data' 
SAY '! 
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7.6. DESCRIBE 


Format: 
Arguments: 


Result: 


Description: 


X+'DESCRIBE' NAME 


NAME -name of a prepared SELECT SQL statement (see PREPARE); 


rc dscr 


re - return code; 
dscr -a nested matrix with 2 rows; this matrix contains as many columns as would the 
table returned by the FETCH operation when applied to the named statement. 


This operation provides information about the columns that would appear in a table resulting from a 
FETCH operation applied to the named statement. Thus, the name should be that of a prepared 
stetment that returns a data set (as a SELECT statement). The column information returned appears 
in the form of a nested matrix. Each item of this matrix is a character vector. 


The first row of the returned matrix contains the column names in the same order as in the table that 
would be returned by a FETCH operation on the named statement. 


The second row of the result matrix contains descriptions of each database column. The following is a 
list of data types reported by AP127 and their meanings: 


Example: 


BIN n_ -binary data of length n; 
BIT - single bit; 


TI - tiny integer (8 bits); 

S - small integer (16 bits); 

I - integer (32 bits); 

BI - big integer (64 bits); 

Dnm -decimal with precision n and scale m; 

F - floating point number; 

Cn - character string of constant length n; 

Vn - character string of variable length, but not more than n; 
Ln - long (length more than 254) character string of variable length, but not more than 
TIME -time; 

DATE - date; 

TS - timestamp; 


UNK - AP127 was not able to recognize the type of a field. 


SAY 'PREP' 'S1i' 'SELECT x FROM ORDERS' 


DISPLAY SAY 'DESCRIBE' 'S1' 


See Soa, Jesds EE AEE woe | 


|OrderID| |CustID| |ProdID| |OrderDate| |Quantity| 
t 1 1 t t t 


— He 


SAY 'PURGE' 'S1! 
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7.7. EXECUTE 
Format: X*+'EXEC' STMT 
Arguments: STMT -text of a valid SQL statement other than a COMMIT, CLOSE, DESCRIBE, 


FETCH, OPEN, ROLLBACK, or SELECT statement. It must not contain 
parameter markers - "?". 


Result: rcn 
re - return code; 
n - number of affected rows; if the number of affected rows is not applicable to an 
SQL statement, or the current driver does not support this feature, the value of n is 
undefined. 
Description: 


This operation executes an SQL statement STMT. If a similar statement needs to be executed many 
times with different values, the CALL operation is more appropriate. 


Example: 


SAY 'EXEC' 'DELETE FROM ORDERS WHERE OrderID>25' 
13 


AP127 Reference Manual 21 


7.8. FETCH 
Format: X«+'FETCH' NAME [opti ... optn] 


Arguments: NAME -name of prepared, opened statement. 


opti -options from the following list: 


"MATRIX! - the result res of the FETCH operation will be a nested matrix 
which has as many rows as have been retrieved by the FETCH 
from the database. Each item of the matrix represents exactly 
one field from the database. NULLs are represented by empty 
vectors. 

'VECTOR' ~ the result res of the FETCH operation will be a nested vector 
every item of which is a matrix that represents a complete 
column of data. Data of type VARCHAR and VARBIN is 
expanded to the full column width. NULLs are converted to Os 
for numeric data and to blanks for character data. 

'SIMPLE' - the result res of the FETCH operation will be a simple matrix 
which has as many rows as have been retrieved by the FETCH 
from the database. This is the disclosed version of 'VECTOR' 
format. Types of retrieved fields must be compatible. Otherwise, 
an error will be returned. 

"LENGTH! - this option causes an extra array to be appended to the result 
when the 'VECTOR' option is in effect. The extra array 
contains the actual lengths of the data before it was changed to 
adapt to the column width. 

'NOLENGTH' -disables the 'LENGTH' option. 

Non-negative integer - row count: the maximum number of table rows that are to 
be returned by a single FETCH operation. If this number is 0, 
AP127 will return maximal possible number of rows. 


Any number of options can be specified in any order. If conflicts occur, the last 
option found will be used. 


re res 


re - return code; 

res -an array containing the data found, if any. The shape and type of the array will be 
vary, depending on the options in effect and the availability of data. If there are 
rows still remaining in the result table after the execution of FETCH, the return 
code will indicate this. 


Description: 


This operation returns the rows of a table that are the result of a statement that returns a data set (as a 
SELECT statement). This statement must be prepared by a PREP operation and opened by an OPEN 
operation. Each successive execution of FETCH will return more rows of the result table until all 
rows have been returned. The number of return rows can be more than the row count parameter set 
by FETCH or by SETOPT. By default, FETCH returns maximal possible number of rows of data. 
AP127 uses a 64K internal buffer. This means that the returned result cannot occupy more than 64K 
of memory. If you want to retrieve more than 64K of data, you have to use FETCH more than once 
(see the example below). 


If the return code rc is 0 O 1 1 23, it means that it is possible that less than all of the rows 
have been retrieved. You should call FETCH until it returns rc equalto 0 0 0 O O. In this 
case res is an empty array of appropriate shape. See example below. Note, that AP127 may return 
0 0 1 1 23 code, if even all rows have been retrieved. In such cases, next call to FETCH will 
return an empty result of appropriate shape. 


Because the result set for a prepared SQL statement is formed when the OPEN operation is 
performed, the SQL statement used in a FETCH operation must be closed by a CLOSE operation 
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when FETCH returns all zeros as a return code. It can be re-opened again using different or the same 
parameters. 


The first element of the result of the INFO operation shows the number of active statements that the 
current ODBC driver can support. When an SQL statement is opened it becomes an active statement. 
If your driver can support only one active statement, you must always retrieve the entire row set, or 
close the statement with a CLOSE operation. Otherwise, other AP127 operations which implicitly 
require an active statement cannot be executed. 


Options set in a FETCH command will be in effect for this FETCH operation only. You should use 
SETOPT command to set fetch options globally. If a FETCH command does not contain one or more 
options, the appropriate global value will be used (set by last SETOPT command). The default global 
values for the fetch operation are: 


'"MATRIX' 'NOLENGTH' 0 


AP127 always returns maximum possible number of records that does not exceed the number of 
records set in the current FETCH command, or set globally by the last SETOPT command. Thus, if 
you don't have specific requirements on the number of records retrieving by the FETCH (that usually 
takes place), you should set the number of records globally to 0. It will reduce the number of calls to 
FETCH command and speed up your application. 


The 'MATRIX' format is the most universal one. You can retrieve any type of information in this 
format. It is very useful, when you need to fetch numeric and character columns of variable length 
together. However this format leaves quite a lot of work for the APL system, when you process the 
results in the APL workspace that can slow down your application. 


The ' VECTOR ' format is useful when character (or binary) data to be retrieved from a database has 
constant length. In such cases you have all advantages of a 'MATRIX' format, but in many cases 
you can save some time on processing your data inside APL. This format requires more efforts in a 
cover APL function that fetches inforamtion from a database, if your data may have a variable length. 


The 'SIMPLE' format is very effective, if you retrieve same type columns from a database. It 
allows to recieve up to 32700 16-bit integers using only one call of the FETCH command. Note, that 
if you retrieve numeric data of different types, AP127 will convert them to the "widest" type. For 
example, if you are retrieving two columns, one of which is integer and another is floating point, the 
result matrix will be a matrix of floating point numbers. 


The AP127 workspace contains three APL defined functions: FETCHM, FETCHV, and FETCHS 
that demonstrate all three approaches to the fetching of data from a database. 
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Example: 


The following example demonstrates a possible FETCH defined function that retrieves data in a 
matrix format. Its right argument must be a SELECT SQL statement, and the optional left argument, 
a parameter list. It returns the entire row set selected from a database by the SELECT statement S. 


R+{A} FETCH S 


[1] R+-SAY 'PREP' 'SS' 


[2] >(0=0DNC '4A')/Li 


[3] R-SAY 'OPEN' 'SS' 


[4] >L2 

[5] ZL1:R-SAY 'OPEN' 
[6] L2:R+SAY 'FETCH' 
[7] L£3:+(RCaA.=0)/L4 


[8] R+-R,[1]SAY 'FETCH' 


[9] >L3 
[10] L4:S+SAY 'CLOSE' 


100 FETCH 'SELECT » FROM ORDERS WHERE ORDERID>?' 


101 1994-05-26 123.45 
102 1994-05-26 345.89 
108 1994-05-30 23.78 
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7.9. GET OPTIONS 
Format: X«+'GETOPT'! 


Arguments: None 


Result: re res 

re - return code; 

res -a four element nested vector containing the current AP127 settings. 
Description: 


This operation returns the current global settings of the FETCH operation options list and the current 
commit mode. The values can be: 

torc +> 'MATRIX' or 'VECTOR' or 'SIMPLE'! 

2>rc +> 'LENGTH' or 'NOLENGTH' 

32rc +> 'AUTO' or 'MANUAL' 

4>rc «+ maximum number of rows to be returned by FETCH 


Global parameters are set by SETOPT command. The defaults are: 
"MATRIX' 'NOLENGTH' 'AUTO' 0 


See the description of FETCH, COMMIT, and ROLLBACK operations for more details. 


Example: 


SAY 'GETOPT' 
MATRIX NOLENGTH AUTO 500 
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7.10. INFO 
Format: X+'INFO! 


Arguments: None 


Result: re inf 
re - return code; 
inf  -a four element integer vector describing the current ODBC driver (see below). 


Description: 
The values of the elements of vector inf are interpreted as follow: 


inf[ 1 ]- the number of active statements that the current driver can support. If this value is 0, it 
means that driver supports unlimited number of active statements, or can't return this 
value. In AP127 only opened SELECT statement not all results of which have been 
retrieved, is an "active statement". Certain AP127 commands use active statements 
implicitly, so you always must leave at least one active statement for the system use. 
Because statement may remain active only after executing OPEN command on a prepared 
SQL statement, you should execute FETCH until it returns all zeros in return code. 

inf[ 2 ]- if this is 0, it means that driver supports automatic commit mode only. In automatic 
commit mode driver commit every transaction by itself and can't perform ROLLBACK 
operations. If this element is 1, it means that driver is in manual commit mode. You 

© should use COMMIT and ROLLBACK operation to close transactions on a database. 

inf[ 3 ]- COMMIT behavior: 

0 - drop: after COMMIT operation on a database, SQL statements must be prepared 
(and re-opened for SELECT statements) again. 

1 - close: after COMMIT operation on a database, SQL statements must be re- 
opened (for SELECT statements), prepared statements do not change their 
status. 

2 - preserve: status of SQL statements is not changed after COMMIT operation. 

inf[4 ]- ROLLBACK behavior: 

0 - drop: after ROLLBACK operation on a database, SQL statements must be 
prepared (and re-opened for SELECT statements) again. 

1 - close: after ROLLBACK operation on a database, SQL statements must be re- 
opened (for SELECT statements), prepared statements do not change their 
status. 

2 - preserve: status of SQL statements is not changed after ROLLBACK operation. 


Example: 
See defined function INFO from the AP127 workspace. 
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7.11. MESSAGE 


Format: X<'MSG' par 
Arguments: par - five element integer vector, or character vector. 
Result: re ertxt state 

re - return code; 


ert xt -character vector, or empty numeric vector; 
state -character vector. 


Description: 
This command returns error message or sets the behavior how AP127 displays errors. 


If the argument of the MSG command is a five element integer vector, it is interpreted as a return 
code of a AP127 command. In this case AP127 will return the text of message that corresponds to 
this return code in errt xt, if any, and the ODBC state code as a character vector in state. For 
AP127 errors state isalways '00000'. 


If the argument is a character vector, AP127 will change the behavior how it displays errors. par 
must be one of the following: 


'OFF! - AP127 does not display a message box in any situation; 
'ERRORS' - AP127 displays a message box only if an error occured (default mode); 
"ALL! - AP127 displays a message box if an error or a warning occured. 


Example: 


SAY 'MSG' (1 00 1 12) 
Statement not found 00000 
SAY 'MSG' ‘ALL! 
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7.12. GET NAMES 
Format: X+«'NAMES' 
Arguments: None 


Result: re names 
re - return code; 
names - character matrix. 


Description: 
This command returns a character matrix containing the names of all prepared SQL statements. It 
can be used together with two other AP127 commands: GET STATEMENT STATE and GET 
STATEMENT TEXT. Names of SQL statements are returned in the rows of the result matrix. 
Example: 


SAY 'NAMES' 
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7.13. OPEN CURSOR 


Format: 


Arguments: 


Result: 


Description: 


X+'OPEN' NAME [(Vi V2 ... Vn)] 


NAME -name of a prepared SQL statement (see PREPARE); 

V1... - value list conforming to the parameter markers in the named SQL statement. The 
number of values in the list must be the same as the number of "?" marks in the 
SQL statement. Each value must be a scalar, a one element simple vector, or a 
simple character vector. Empty vectors are treated as NULL values (the 
appropriate columns must allow NULL value). 


ren 
re - return code; 
n - number of affected rows; the current driver may not support this feature, for such 


drivers the value of n is undefined. 


This operation opens a cursor for SQL statement that returns a result set and that has been previously 
prepared. If named SQL statement was defined with parameter markers, then the values to be 
substituted before executing a FETCH must be supplied at this time. You must open cursor before 
using the FETCH operation to retrieve the results. 


If you have any problems using the CALL and OPEN commands with parameters, please contact 
Lingo Allegro for assistance. In any case you can avoid the use of dynamic parameters in SQL 
Statements by applying the appropriate transformations in APL . 


Example: 


SAY 'PREP' 'Si' "SELECT * FROM ORDERS WHERE 


OrderDate>?! 


0 


SAY 'OPEN' 'Si' '1994-05-25! 


AP127 Reference Manual 29 


7.14. PREPARE 
Format: X+'PREP' NAME TEXT 


Arguments: 

NAME -a valid statement name up to 4 characters in length, beginning with a letter. It is 
used to idnetify the statement in subsequent CALL, OPEN, FETCH, CLOSE, 
DESCRIBE, PURGE, STATE, and STMT operations; 

TEXT -text of a valid SQL statement other than DESCRIBE, OPEN, CLOSE, COMMIT, 
CALL, ROLLBACK, FETCH, and some others. This statement may include SQL 
parameter markers indicated by "?". Parameter markers will be substituted with 
actual values by a subsequent OPEN or CALL operation. 


Result: re (10) 
ce - return code; 


Description: 

This operation prepares an SQL statement for subsequent CALL or OPEN operations. The statement 
is named by an APL programmer, to distinguish it from other prepared statements. Later, this name 
is supplied to other AP127 operations that require a prepared statement as an argument. If the 
statement is a SELECT SQL statement, then to cause it to be executed, you must subsequently use an 
OPEN operation, one or more FETCH operations, and a CLOSE operation on the prepared statement. 
To cause a non-SELECT SQL statement to be executed, you must subsequently use a CALL operation 
on the prepared statement. Supplying a name that is already that of an prepared statement in AP127 
causes a PURGE operation to be performed before the PREPARE operation. 


Example: 
SAY 'PREP' 'S1' 'SELECT x FROM ORDERS! 


SAY 'PREP' 'S2' 'SELECT x FROM ORDERS WHERE OrderID=7' 
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7.15. PURGE 


Format: X+'PURGE' NAME 
Arguments: 
NAME -character vector that represents name of a prepared statement, or empty character 
vector. 
Result: re (10) 
re ~ return code; 


Description: 
This operation deletes a named statement and frees all ODBC resources connected with this 
statement. If the argument is empty vector, all prepared statements will be deleted. 


Example: 
SAY 'PREP' 'S1' 'SELECT x FROM ORDERS' 


SAY 'PURGE' 'S1' 


AP127 Reference Manual 31 


7.16. ROLLBACK WORK 
Format: X+'ROLLBACK' 
Arguments: None 


Result: rc (10) 


re ~ return code; 


Description: 

This operation backs out any database modifications made since the last COMMIT or ROLLBACK 
operation. AP127 may perform different actions when executing this operation. If the fourth element 
of the result of INFO command is: 

0 - all prepared statements are purged (DELETE mode); 

1 - all opened statements are closed; they can be re-opened without preparation (CLOSE 
mode); 

2 - prepared statements do not change their states (PRESERVE mode); 


If the second element of the result of INFO command is 0, the current ODBC driver does not support 
the manual COMMIT mode. That is, all transactions are committed immediately by the driver. You 
can't ROLLBACK transactions. 


By default, AP127 uses the AUTOCOMMIT mode. If the current ODBC driver allows the MANUAL 
COMMIT mode, you must use the SETOPT command to set AP127 to this mode. 
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7.17. SET OPTIONS 


Format: X*+'SETOPT' opti ... optn 


Arguments: 
opt 1...- options from the following list: 


"MATRIX! - the result res of the FETCH operation will be a nested matrix 
which has as many rows as have been retrieved by the FETCH 
from the database. Each item of the matrix represents exactly 
one field from the database. NULLs are represented by empty 
vectors. 


'VECTOR' - the result res of the FETCH operation will be a nested vector 
every item of which is a matrix that represents a complete 
column of data. Data of type VARCHAR and VARBIN is 
expanded to the full column width. NULLs are converted to 0s 
for numeric data and to blanks for character data. 


"SIMPLE! - the result res of the FETCH operation will be a simple matrix 
which has as many rows as have been retrieved by the FETCH 
from the database. This is the disclosed version of 'VECTOR! 
format. Types of retrieved fields must be compatible. Otherwise, 
an error will be returned. 


‘LENGTH! - this option causes an extra array to be appended to the result 
when the 'VECTOR' option is in effect. The extra array 
contains the actual lengths of the data before it was changed to 
adapt to the column width. 


'NOLENGTH' -disables the 'LENGTH' option. 


'AUTO! - this option causes AP127 to commit database transactions 
automatically. When AP127 is in this mode you can't rollback 
transactions. 

"MANUAL! - this option sets AP127 to the manual commit mode. You have to 


use COMMIT and ROLLBACK commands to close active 
transactions. If the second element of the result of INFO 
command is 0, you can not use this option (see the description of 
INFO command). 


Non-negative integer - row count: the maximum number of table rows that are to 
be returned by a single FETCH operation. If it is 0, maximal 
possible number of rows will be returned. 


Result: re (10) 
re - return code; 


Description: 

This operation changes the current settings of the control options that affect the result of a FETCH 
operation. It also controls the current COMMIT/ROLLBACK mode. FETCH options will apply to 
future FETCH operations, unless they are reset by a subsequent SETOPT operation, or temporarily 
overridden in the options list argument of the FETCH operation. COMMIT/ROLLBACK options can 
be set by this command only. Any number of options above can be specified in any order. If conflicts 
occur, the last option value found will be used. By default, AP127 uses "MATRIX! 
'"NOLENGTH' '‘AUTO' Q. 

See the descriptions of FETCH, COMMIT, and ROLLBACK operations for more details. 


Example: 
SAY 'SETOPT' 'VECTOR' 1000 'LENGTH' 
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7.18. GET STATEMENT STATE 


Format: X«'STATE' NAME 
Arguments: 
NAME -character vector that represents name of a prepared statement, or empty character 
vector. 
Result: re state 
re - return code; 


state - two element integer vector (state vector); 


Description: 
This operation returns the current state of a prepared (by a PREPARE operation) SQL statement. The 
elements of state vector are interpreted as follow: 


state[1i]: 
1 -non-SELECT SQL statement; 
2 -SELECT statement; 


state[2]: 
o -non-prepared statement; 
1 -prepared statement; 
2 -opened statement; 


Example: 

SAY 'PREP' 'S1' "SELECT x FROM ORDERS' 
SAY 'STATE' ‘Si! 

214 
SAY 'OPEN' 'S1' 

0 
SAY 'STATE' 'S1' 

2 2 
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7.19. GET STATEMENT TEXT 
Format: X+'STMT' NAME 


Arguments: 


NAME -character vector that represents name of a prepared statement. 


Result: rc text 


re - return code; 
text -character vector, 


Description: 
This operation returns the original text of a prepared SQL statement. 


Example: 
SAY 'PREP' 'S1' 'SELECT x FROM ORDERS' 


SAY 'STMT' 'S1' 
SELECT * FROM ORDERS 
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7.20. TABLES 


Format: (1) X+'TABLES' qual owner name type 
(2) X«'TABLES' 
Arguments: 
qual -a character vector that represents table qualifier(s), or empty character vector; 
owner -acharacter vector that represents table owner(s), or empty character vector; 
name -a character vector that represents table name(s), or empty character vector; 
type -a character vector that represents table type(s), or empty character vector. 
Result: re list 
re - return code; 
list -nested matrix with 5 columns; each item is a simple character vector, or empty 
vector; 


Description: 


This operation returns the list of available tables in the current database. Every row of the result 
matrix describes one table as follow: 


list[;1] -table qualifier; 
list[;2] -table owner; 
list[;3] -table name; 
list[;4] -table type; 
list[;5] -table description; 


The command arguments are defined as search patterns that may include escape characters (usually 
"%" and "*"). If an argument is empty, all corresponding objects will be selected. Not all ODBC 
drivers are able to support searching using all above parameters. If this operation returns warning 23 
(table incomplete), it means that AP127 could not return all data from a database. You have to call 
TABLES again until the return code will be 00000. When the TABLES command is called not 
the first time (when fetching the rest of the result set), its arguments are ignored. Simple function 
shown below (from the AP127 workspace) retreives information about all tables in the current 
database. Instead of using this command, you can use SELECT statement on appropriate system 
table (see your DBMS manual for details). 


If the current ODBC driver supports table types, they should be specified as a list of the following 
values: 
'TABLE', 'VIEW', 'SYSTEM TABLE', andsoon. 


Example: 


The following example lists all tables and views in the current database: 


R<«TABLES ARGS 
[1] R+0 Spctt 
[2] R+RZSAY (c'TABLES'),ARGS o +(RCv.#0)/0LC 


TABLES tt tt tt "UUTABLE'' ,''VIEW' tt 
C:\ACCESS\MYBASE .MDB CUSTOMER TABLE 
C:\ACCESS\MYBASE .MDB PRODUCT TABLE 
C:\ACCESS\MYBASE .MDB ORDERS TABLE 


The following example lists the names of all tables which begin with "P": 


TABLES '' '' 'P%t '''TABLE''! 
C:\ACCESS\MYBASE . MDB PRODUCT TABLE 
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7.21. WAKEUP 


Format: X«'WAKEUP' [time (string]] 


Arguments: 


Result: 


time - timeout of inactivity in minutes; 
string -acharacter vector that represents an SQL statement; 


re (time string) 


re - return code; 
time - timeout of inactivity in minutes; 
string -a character vector that represents an SQL statement; 


Description: 


Some databases (such as IBM DB2 on a mainframe) may automatically terminate the communication 
link after a certain period of inactivity. If your application remains idle but needs an active 
communication link all the time, you can use the WAKEUP command. The first argument of the 
WAKEUP command sets the timeout value in minutes (1 to 120). The second parameter defines a 
SQL statement which will be automatically sent to the remote database server when AP127 inactivity 
exceeds the timeout period. This command is then repeated after AP127 activity again exceeds the 
timeout period, and so on. See the example below. 


If the string parameter is omitted, empty string will be used (won't work for all databases). If 
both parameters omitted, the second item of result is two element nested vector. The first element is 
current wake up timeout, and the second element is the current wake up SQL statement. In other 
cases, the result is empty numeric vector. If AP127 reports the timeout value as ~1, it means that 
timeout actions currently turned off. 


If WAKEUP command has only first argument, which is 0, AP127 won't perform any wake up actions 
(default situation). 


Note, that AP127 will not report any error messages, which could be caused by the execution of wake 
up SQL statement. It means, that you can use a SQL statement that is syntactically or semantically 
incorrect as a wake up string. 


Example: 


After execution of this expression, AP127 will send the statement USE MYDATABASE to the 
current data source after each 15 minutes inactivity: 


SAY 'WAKEUP' 15 'USE MYDATABASE' 


The following example obtains current timeout and wake up statement: 


SAY 'WAKEUP' 
15 USE MYDATABASE 


The following example cancels wake up actions: 


SAY 'WAKEUP' 0 


SAY 'WAKEUP' 
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